/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client.service;

import java.util.Map;

import com.google.gwt.user.client.rpc.IsSerializable;
import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.SerializableException;

/**
 * <p>Provide a API for the resource bundle service.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li> declare the service context name used for lookup
 * 	<li> return a resource bundle using the locale associated with the session
 * 	<li> return a resource bundle using the specified locale
 * 	<li> get and set the locale for the http session
 * </ul>
 * </p>
 * <p>Collaborators:
 * <ul>
 * 	<li> MissingResourceException - thrown when bundles are not found
 * 	<li> LocaleInfo - Gems representation of a locale
 * </ul>
 * </p>
 * 
 * @author Ashin Wimalajeewa (ash)
 */
public interface ResourceBundleRpc extends RemoteService {
	public String SERVICE_CTX = "/gems.util.resourcebundle";
	
	/**
	 * Query a resource bundle to replace text in UI or report related widgets.
	 * 
	 * @gwt.typeArgs <java.lang.String, java.lang.String>
	 * @param name - the base name of bundle to load resource from 
	 * @return - a mapped representation of the bundle
	 * @throws MissingResourceException if the server-side ResourceBundle facility is
	 * 			unable to resolve the bundle from the classpath.
	 */
	public Map getResourceBundle(String name) throws MissingResourceException;
	
	/**
	 * Query a resource bundle to replace text in UI or report related widgets.
	 * 
	 * @gwt.typeArgs <java.lang.String, java.lang.String>
	 * @param name - the base name of bundle to load resource from 
	 * @param locale - the locale to use which will often target a derivative resource
	 * 					bundle. If null or {@link LocaleInfo#HTTP_REQUEST_LOCALE} is used,
	 * 					then the locale associated with the http request will be used. 
	 * @return - a mapped representation of the bundle
	 * @throws MissingResourceException if the server-side ResourceBundle facility is
	 * 			unable to resolve the bundle from the classpath.
	 */
	public Map getResourceBundle(String name, LocaleInfo locale) throws MissingResourceException;
	
	/**
	 * @return the locale currently associated with the session
	 */
	public LocaleInfo getSessionsLocale();
	
	/**
	 * Command that sets the locale that is to be hereafter used for bundle lookups
	 * @param locale
	 */
	public void setSessionsLocale(LocaleInfo locale);
	
	/**
	 * <p>Gems representation of a java.util.MissingResourceException object.</p>
	 */
	public class MissingResourceException extends SerializableException {
		private static final long serialVersionUID = 1L;
		public String key;
		public String className;
		
		public MissingResourceException() {
		}
		
		public MissingResourceException(String msg, String clzNm, String ky) {
			className = clzNm;
			key = ky;
		}
	}
	
	/**
	 * <p>Gems representation of a java.util.Locale object.</p>
	 */
	public class LocaleInfo implements IsSerializable {
		final static public LocaleInfo HTTP_REQUEST_LOCALE = null;
		
		private int hashCodeValue;
		public String language;
		public String country;
		public String variant;
		
	    public LocaleInfo(String language, String country, String variant) {
	        this.language = language;
	        this.country = country;
	        this.variant = variant;
	    }
	    
	    public LocaleInfo(String language, String country) {
	    	this(language, country, "");
	    }
		
	    public LocaleInfo(String language) {
	    	this(language, "", "");
	    }

	    public LocaleInfo() {
	    }
	    
	    public int hashCode() {
	        int hc = hashCodeValue;
	        if (hc == 0) {
	            hc = (language.hashCode() << 8) ^ country.hashCode() ^ (variant.hashCode() << 4);
	            hashCodeValue = hc;
	        }
	        return hc;
	    }
	    
	    public String toString() {
	        boolean l = language.length() != 0;
	        boolean c = country.length() != 0;
	        boolean v = variant.length() != 0;
	        StringBuffer result = new StringBuffer(language);
	        if (c||(l&&v)) {
	            result.append('_').append(country); // This may just append '_'
	        }
	        if (v&&(l||c)) {
	            result.append('_').append(variant);
	        }
	        return result.toString();
	    }
	    
	}
}
